home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / array.n < prev    next >
Encoding:
Text File  |  1994-12-17  |  4.4 KB  |  119 lines
  1. '\"
  2. '\" Copyright (c) 1993-1994 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) array.n 1.3 94/12/17 16:17:39
  9. '\" 
  10. .so man.macros
  11. .HS array tcl 7.4
  12. .BS
  13. '\" Note:  do not modify the .SH NAME line immediately below!
  14. .SH NAME
  15. array \- Manipulate array variables
  16. .SH SYNOPSIS
  17. \fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR?
  18. .BE
  19.  
  20. .SH DESCRIPTION
  21. .PP
  22. This command performs one of several operations on the
  23. variable given by \fIarrayName\fR.
  24. Unless otherwise specified for individual commands below,
  25. \fIarrayName\fR must be the name of an existing array variable.
  26. The \fIoption\fR argument determines what action is carried
  27. out by the command.
  28. The legal \fIoptions\fR (which may be abbreviated) are:
  29. .TP
  30. \fBarray anymore \fIarrayName searchId\fR
  31. Returns 1 if there are any more elements left to be processed
  32. in an array search, 0 if all elements have already been
  33. returned.
  34. \fISearchId\fR indicates which search on \fIarrayName\fR to
  35. check, and must have been the return value from a previous
  36. invocation of \fBarray startsearch\fR.
  37. This option is particularly useful if an array has an element
  38. with an empty name, since the return value from
  39. \fBarray nextelement\fR won't indicate whether the search
  40. has been completed.
  41. .TP
  42. \fBarray donesearch \fIarrayName searchId\fR
  43. This command terminates an array search and destroys all the
  44. state associated with that search.  \fISearchId\fR indicates
  45. which search on \fIarrayName\fR to destroy, and must have
  46. been the return value from a previous invocation of
  47. \fBarray startsearch\fR.  Returns an empty string.
  48. .TP
  49. \fBarray exists \fIarrayName\fR
  50. .VS
  51. Returns 1 if \fIarrayName\fR is an array variable, 0 if there
  52. is no variable by that name or if it is a scalar variable.
  53. .VE
  54. .TP
  55. \fBarray get \fIarrayName\fR
  56. .VS
  57. Returns a list containing pairs of elements.  The first
  58. element in each pair is the name of an element in \fIarrayName\fR
  59. and the second element of each pair is the value of the
  60. array element.  The order of the pairs is undefined.
  61. If \fIarrayName\fR isn't the name of an array variable, or if
  62. the array contains no elements, then an empty list is returned.
  63. .VE
  64. .TP
  65. \fBarray names \fIarrayName\fR ?\fIpattern\fR?
  66. Returns a list containing the names of all of the elements in
  67. .VS
  68. the array that match \fIpattern\fR (using the glob-style matching
  69. rules of \fBstring match\fR).
  70. If \fIpattern\fR is omitted then the command returns all of
  71. the element names in the array.
  72. If there are no (matching) elements in the array, or if \fIarrayName\fR
  73. isn't the name of an array variable, then an empty string is
  74. returned.
  75. .VE
  76. .TP
  77. \fBarray nextelement \fIarrayName searchId\fR
  78. Returns the name of the next element in \fIarrayName\fR, or
  79. an empty string if all elements of \fIarrayName\fR have
  80. already been returned in this search.  The \fIsearchId\fR
  81. argument identifies the search, and must have
  82. been the return value of an \fBarray startsearch\fR command.
  83. Warning:  if elements are added to or deleted from the array,
  84. then all searches are automatically terminated just as if
  85. \fBarray donesearch\fR had been invoked; this will cause
  86. \fBarray nextelement\fR operations to fail for those searches.
  87. .TP
  88. \fBarray set \fIarrayName list\fR
  89. .VS
  90. Sets the values of one or more elements in \fIarrayName\fR.
  91. \fIlist\fR must have a form like that returned by \fBarray get\fR,
  92. consisting of an even number of elements.
  93. Each odd-numbered element in \fIlist\fR is treated as an element
  94. name within \fIarrayName\fR, and the following element in \fIlist\fR
  95. is used as a new value for that array element.
  96. .VE
  97. .TP
  98. \fBarray size \fIarrayName\fR
  99. Returns a decimal string giving the number of elements in the
  100. array.
  101. .VS
  102. If \fIarrayName\fR isn't the name of an array then 0 is returned.
  103. .VE
  104. .TP
  105. \fBarray startsearch \fIarrayName\fR
  106. This command initializes an element-by-element search through the
  107. array given by \fIarrayName\fR, such that invocations of the
  108. \fBarray nextelement\fR command will return the names of the
  109. individual elements in the array.
  110. When the search has been completed, the \fBarray donesearch\fR
  111. command should be invoked.
  112. The return value is a
  113. search identifier that must be used in \fBarray nextelement\fR
  114. and \fBarray donesearch\fR commands; it allows multiple
  115. searches to be underway simultaneously for the same array.
  116.  
  117. .SH KEYWORDS
  118. array, element names, search
  119.